home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / forth / pfe-0.000 / pfe-0 / pfe-0.9.13 / help / Please.help < prev    next >
Encoding:
Text File  |  1995-04-04  |  3.2 KB  |  104 lines
  1. ##### This file is obsolete, online doc can now be derived from the original
  2.       dpANS text files #####
  3.  
  4. Dear Forth friend,
  5.  
  6. when you are using a free Forth system then you often miss
  7. documentation and goodies like online help. With the ANS we have a
  8. chance to change this unfortunate situation easily.
  9.  
  10. Wouldn't it be nice if you could say
  11.  
  12.     "HELP FILE-POSITION"
  13.  
  14. and the system would respond with
  15.  
  16.     "FILE-POSITION ( file-id --- ud ior ) [ANS]
  17.      `ud' is the current file position for the file identified by
  18.      `file-id'. `ior' is 0 if no error occured otherwise it is an
  19.      error-code >0."
  20.  
  21. Unfortunately it is quite a lot of work to type all that stuff.  If we
  22. could share this work among maybe - 10 - people, then each one of us
  23. has a job for one weekend or so. With your help the online help effort
  24. can be easily finished within one month.
  25.  
  26. If you like to participate in that effort please send mail to
  27. duz@roxi.rz.fht-mannheim.de and tell me
  28.  
  29.     - the words you'd like to document. Choose one of the smaller
  30.       word sets or an alphabetic range in the core word set. If
  31.       you have no special preference it's just as well.
  32.  
  33.     - an estimation when you'd like best to do the thing.
  34.  
  35. I'll try to coordinate a little.
  36.  
  37. The text you write will be free software. Anybody shall be free to use
  38. it in his system.
  39.  
  40.  
  41. File format:
  42. ============
  43.  
  44. ........|column 0
  45.     v
  46.     # this is a comment, e.g.:
  47.     # The optional File Access word set
  48.     # xxx@yyy.zzz.aaa <John Miller> wrote the following doc-strings
  49.  
  50.     : WORD-NAME ( input params --- results ) [ANS]
  51.     whatever is neccessary to describe WORD-NAME. You can use newlines
  52.     and at most one empty line to separate paragraphs. Don't exceed
  53.     column 72 in case you want to print it some day.
  54.  
  55.     : THIS-IS-THE-NEXT-WORD ....
  56.  
  57. the `:' (followed by one space of course) is just a convenience for us
  58. Forth-freaks. It marks the next word if it is found in column 0.
  59.  
  60. There is no need to order the words.
  61. I wrote two little utility programs to access the help strings:
  62.  
  63.     helpindex [-o outfile] file1 file2 ...
  64.         reads files in the above format. Writes an index
  65.         to all files to the standard output or to the
  66.         specified outfile.
  67.  
  68.     showhelp index word1 word2 ...
  69.         uses the index file created by helpindex to access
  70.         the source help files and displays the documentation
  71.         strings to all words specified.
  72.  
  73. For an example refer to the file forth-83.hlp where some words are
  74. documented that are non-standard extensions in one system.
  75.  
  76.  
  77. Style
  78. =====
  79.  
  80. Of course there is already a text that precisely describes all
  81. ANS-Forth words, the standard. I think it would be better not to copy
  82. this text for two reasons:
  83.  
  84.     - it's copyrighted
  85.     - some things can be expressed a little more comprehensive.
  86.  
  87. On the other hand it is difficult to write anything else on ROT but:
  88.  
  89.     Rotate the top three stack entries. (dpANS-6 6.1.2160)
  90.  
  91. I guess writing the same sentence cannot be considered a copyright
  92. violation.
  93.  
  94. Stack comments should use the abbreviations from the dpANS-6, table
  95. 3.1, page 8.
  96.  
  97. For the implementor wishing to use this text body it would be nice if
  98. the phrases "ambigous condition" and "implementation defined" would be
  99. used whereever the ANS uses them. Reason: these can be found easily
  100. with the text editor and replaced by the specification his system's
  101. behaviour.
  102.  
  103. Suggestions for improvements are welcome.
  104.